<!DOCTYPE html><html><head>
<title>wip - Word Interpreter</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'wip.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; 2007-2010 Andreas Kupries &amp;lt;andreas_kupries@users.sourceforge.net&amp;gt;
   -->
<!-- wip.n
   -->
<body><hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
&#124; <a href="../../../../toc.html">Main Table Of Contents</a>
&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">wip(n) 2.2 tcllib &quot;Word Interpreter&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>wip - Word Interpreter</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">GENERAL BEHAVIOUR</a></li>
<li class="doctools_section"><a href="#section3">CLASS API</a></li>
<li class="doctools_section"><a href="#section4">OBJECT API</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">wip <span class="opt">?2.2?</span></b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.3?</span></b></li>
<li>package require <b class="pkgname">struct::set</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::wip</b> <i class="arg">wipName</i> <i class="arg">engine</i> <i class="arg">arg</i>...</a></li>
<li><a href="#2"><b class="cmd">def</b> <i class="arg">name</i></a></li>
<li><a href="#3"><b class="cmd">def</b> <i class="arg">name</i> <i class="arg">method_prefix</i></a></li>
<li><a href="#4"><b class="cmd">wipName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><b class="cmd">wip::dsl</b> <span class="opt">?<i class="arg">suffix</i>?</span></a></li>
<li><a href="#6"><i class="arg">wipName</i> <b class="method">def</b> <i class="arg">name</i> <span class="opt">?<i class="arg">method_prefix</i>?</span></a></li>
<li><a href="#7"><i class="arg">wipName</i> <b class="method">defl</b> <i class="arg">names</i></a></li>
<li><a href="#8"><i class="arg">wipName</i> <b class="method">defd</b> <i class="arg">dict</i></a></li>
<li><a href="#9"><i class="arg">wipName</i> <b class="method">deflva</b> <i class="arg">name</i>...</a></li>
<li><a href="#10"><i class="arg">wipName</i> <b class="method">defdva</b> (<i class="arg">name</i> <i class="arg">method_prefix</i>)...</a></li>
<li><a href="#11"><i class="arg">wipName</i> <b class="method">undefl</b> <i class="arg">names</i></a></li>
<li><a href="#12"><i class="arg">wipName</i> <b class="method">undefva</b> <i class="arg">name</i>...</a></li>
<li><a href="#13"><i class="arg">wipName</i> <b class="method">unknown</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#14"><i class="arg">wipName</i> <b class="method">runl</b> <i class="arg">wordlist</i></a></li>
<li><a href="#15"><i class="arg">wipName</i> <b class="method">run</b> <i class="arg">word</i>...</a></li>
<li><a href="#16"><i class="arg">wipName</i> <b class="method">run_next</b></a></li>
<li><a href="#17"><i class="arg">wipName</i> <b class="method">run_next_while</b> <i class="arg">acceptable</i></a></li>
<li><a href="#18"><i class="arg">wipName</i> <b class="method">run_next_until</b> <i class="arg">rejected</i></a></li>
<li><a href="#19"><i class="arg">wipName</i> <b class="method">run_next_if</b> <i class="arg">acceptable</i></a></li>
<li><a href="#20"><i class="arg">wipName</i> <b class="method">run_next_ifnot</b> <i class="arg">rejected</i></a></li>
<li><a href="#21"><i class="arg">wipName</i> <b class="method">next</b></a></li>
<li><a href="#22"><i class="arg">wipName</i> <b class="method">peek</b></a></li>
<li><a href="#23"><i class="arg">wipName</i> <b class="method">peekall</b></a></li>
<li><a href="#24"><i class="arg">wipName</i> <b class="method">insertl</b> <i class="arg">at</i> <i class="arg">wordlist</i></a></li>
<li><a href="#25"><i class="arg">wipName</i> <b class="method">replacel</b> <i class="arg">wordlist</i></a></li>
<li><a href="#26"><i class="arg">wipName</i> <b class="method">pushl</b> <i class="arg">wordlist</i></a></li>
<li><a href="#27"><i class="arg">wipName</i> <b class="method">addl</b> <i class="arg">wordlist</i></a></li>
<li><a href="#28"><i class="arg">wipName</i> <b class="method">insert</b> <i class="arg">at</i> <i class="arg">word</i>...</a></li>
<li><a href="#29"><i class="arg">wipName</i> <b class="method">replace</b> <i class="arg">word</i>...</a></li>
<li><a href="#30"><i class="arg">wipName</i> <b class="method">push</b> <i class="arg">word</i>...</a></li>
<li><a href="#31"><i class="arg">wipName</i> <b class="method">add</b> <i class="arg">word</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a micro interpreter for lists of words. Domain
specific languages based on this will have a bit of a Forth feel, with
the input stream segmented into words and any other structuring left
to whatever the language desired. Note that we have here in essence
only the core dispatch loop, and no actual commands whatsoever, making
this definitely only a Forth feel and not an actual Forth.</p>
<p>The idea is derived from Colin McCormack's <b class="package"><a href="../treeql/treeql.html">treeql</a></b> processor,
modified to require less boiler plate within the command
implementations, at the expense of, likely, execution speed. In
addition the interface between processor core and commands is more
complex too.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">GENERAL BEHAVIOUR</a></h2>
<p>Word interpreters have a mappping from the names of the language
commands they shall recognize to the methods in the engine to invoke
for them, and possibly fixed arguments for these methods. This mapping
is largely static, however it is possible to change it during the
execution of a word list (= program).</p>
<p>At the time a language command is defined the word interpreter will
use <b class="package"><a href="../snit/snit.html">snit</a></b>'s introspection capabilities to determine the
number of arguments expected by the method of the egnine, and together
with the number of fixed arguments supplied in the method prefix of
the mapping it then knows how many arguments the language command is
expecting. This is the command's <i class="term">arity</i>. Variable-argument
methods (i.e. with the last argument named <i class="arg">args</i>) are <em>not</em>
allowed and will cause the word interpreter to throw an error at
definition time.</p>
<p>Note that while I said <b class="package"><a href="../snit/snit.html">snit</a></b>'s abilities the engine object
can be written in any way, as long as it understands the method
<b class="method">info args</b>, which takes a method name and returns the list
of arguments for that method.</p>
<p>When executing a list of words (aka program) the first word is always
taken as the name of a language command, and the next words as its
arguments, per the <i class="term">arity</i> of the command. Command and argument
words are removed from the list and then associated method of the
engine is executed with the argument words. The process then repeats
using the then-first word of the list.</p>
<p>Note that the methods implementing the language commands may have full
access to the list of words and are allowed to manipulate as they see
fit.</p>
<ol class="doctools_enumerated">
<li><p>This means, for example, that while we cannot specify
variable-argument methods directly they can consume words after their
fixed arguments before returning to the execution loop. This may be
under the control of their fixed arguments.</p></li>
<li><p>Another possibility is the use of method <b class="method">run_next</b> and its
variants to execute commands coming after the current command,
changing the order of execution.</p></li>
<li><p>Execution can be further changed by use of the program accessor
methods which allow a command implementation to modify the remaining
list of words (insert, replace, prepend, append words) without
executing them immediately.</p></li>
<li><p>At last the basic <b class="method">run</b> methods save and restore an existing
list of words when used, enabling recursive use from within command
implementations.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CLASS API</a></h2>
<p>The main command of the package is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::wip</b> <i class="arg">wipName</i> <i class="arg">engine</i> <i class="arg">arg</i>...</a></dt>
<dd><p>The command creates a new word interpreter object with an associated
global Tcl command whose name is <i class="arg">wipName</i>. If however the string
<b class="const">%AUTO%</b> was used as object name the package will generate its
own unique name for the object.</p>
<p>The <i class="arg">engine</i> is the object the word interpreter will dispatch all
recognized commands to, and the <i class="arg">arg</i>uments are a word list which
defines an initial mapping from language words to engine methods.</p>
<p>The recognized language of this word list is</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">def</b> <i class="arg">name</i></a></dt>
<dd><p>Defines <i class="arg">name</i> as command of the language, to be mapped to a
method of the <i class="arg">engine</i> having the same name.</p></dd>
<dt><a name="3"><b class="cmd">def</b> <i class="arg">name</i> <i class="arg">method_prefix</i></a></dt>
<dd><p>Defines <i class="arg">name</i> as command of the language, to be mapped to the
method of the <i class="arg">engine</i> named in the <i class="arg">method_prefix</i>.</p></dd>
</dl>
<p>The returned command may be used to invoke various operations on the
object.  It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">wipName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl></dd>
</dl>
<p>The package additionally exports the command:</p>
<dl class="doctools_definitions">
<dt><a name="5"><b class="cmd">wip::dsl</b> <span class="opt">?<i class="arg">suffix</i>?</span></a></dt>
<dd><p>This command is for use within snit types which wish to use one or
more wip interpreters as a component. Use within the type definition
installs most of the boilerplate needed to setup and use a word
interpreter.</p>
<p>It installs a component named <em>wip</em>, and a method
<b class="method">wip_setup</b> for initializing it. This method has to be called
from within the constructor of the type using the word interpreter.
If further installs a series of procedures which make the object API
of the word interpreter directly available to the type's methods,
without having to specify the component.</p>
<p><em>Note</em> that this does and cannot install the language to
interpret, i.e. the mapping from words to engine methods.</p>
<p>It is possible to instantiate multiple word interpreter components
within a type by using different suffices as arguments to the command.
In that case the name of the component changes to
'wip_<b class="variable">$suffix</b>', the setup command becomes
'wip_<b class="variable">$suffix</b>_setup' and all the procedures also get the suffix
'_<b class="variable">$suffix</b>'.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">OBJECT API</a></h2>
<p>The following commands are possible for word interpreter objects:</p>
<dl class="doctools_definitions">
<dt><a name="6"><i class="arg">wipName</i> <b class="method">def</b> <i class="arg">name</i> <span class="opt">?<i class="arg">method_prefix</i>?</span></a></dt>
<dd><p>Defines a language command <i class="arg">name</i> and maps it to the method named
in the engine's <i class="arg">method_prefix</i>. If the <i class="arg">method_prefix</i> name
is not specified it is simply the name of the language command.</p></dd>
<dt><a name="7"><i class="arg">wipName</i> <b class="method">defl</b> <i class="arg">names</i></a></dt>
<dd><p>Defines a series of language commands, specified through the list of
<i class="arg">names</i>, all of which are mapped to engine methods of the same
name.</p></dd>
<dt><a name="8"><i class="arg">wipName</i> <b class="method">defd</b> <i class="arg">dict</i></a></dt>
<dd><p>Defines a series of language commands, specified through the
dictionary <i class="arg">dict</i> of names and method prefixes.</p></dd>
<dt><a name="9"><i class="arg">wipName</i> <b class="method">deflva</b> <i class="arg">name</i>...</a></dt>
<dd><p>As method <b class="method">defl</b>, however the list of names is specified
through multiple arguments.</p></dd>
<dt><a name="10"><i class="arg">wipName</i> <b class="method">defdva</b> (<i class="arg">name</i> <i class="arg">method_prefix</i>)...</a></dt>
<dd><p>As method <b class="method">defd</b>, however the dictionary of names and method
prefixes is specified through multiple arguments.</p></dd>
<dt><a name="11"><i class="arg">wipName</i> <b class="method">undefl</b> <i class="arg">names</i></a></dt>
<dd><p>Removes the named series of language commands from the mapping.</p></dd>
<dt><a name="12"><i class="arg">wipName</i> <b class="method">undefva</b> <i class="arg">name</i>...</a></dt>
<dd><p>As method <b class="method">undefl</b>, however the list of names is specified
through multiple arguments.</p></dd>
<dt><a name="13"><i class="arg">wipName</i> <b class="method">unknown</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>Sets the handler for unknown words to <i class="arg">cmdprefix</i>. This command
prefix takes one argument, the current word, and either throws some
error, or returns the result of executing the word, as defined by the
handler. The default handler simply throws an error.</p></dd>
<dt><a name="14"><i class="arg">wipName</i> <b class="method">runl</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Treats the list of words in <i class="arg">wordlist</i> as a program and executes
the contained command one by one. The result of the command executed
last is returned as the result of this command.</p>
<p>The <i class="arg">wordlist</i> is stored in the object for access by the other
<i class="term">run</i>-methods, and the general program accessor methods (see
below). A previously stored wordlist is saved during the execution of
this method and restored before it returns. This enables the recursive
execution of word lists within word lists.</p></dd>
<dt><a name="15"><i class="arg">wipName</i> <b class="method">run</b> <i class="arg">word</i>...</a></dt>
<dd><p>As method <b class="method">runl</b>, however the list of words to execute is
specified through multiple arguments.</p></dd>
<dt><a name="16"><i class="arg">wipName</i> <b class="method">run_next</b></a></dt>
<dd><p>Low-level method. Determines the next word in the list of words, and
its arguments, and then executes it. The result of the executed word
is the result of this method.</p>
<p>Exposed for use within command implementations.
The methods <b class="method">run</b> and <b class="method">runl</b> use it to execute words
until their word list is exhausted.</p></dd>
<dt><a name="17"><i class="arg">wipName</i> <b class="method">run_next_while</b> <i class="arg">acceptable</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> as long as the
next word is in the set of <i class="arg">acceptable</i> words, and the program is
not empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="18"><i class="arg">wipName</i> <b class="method">run_next_until</b> <i class="arg">rejected</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> until the next
word is in the set of <i class="arg">rejected</i> words, and the program is not
empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="19"><i class="arg">wipName</i> <b class="method">run_next_if</b> <i class="arg">acceptable</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> if the next
word is in the set of <i class="arg">acceptable</i> words, and the program is not
empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="20"><i class="arg">wipName</i> <b class="method">run_next_ifnot</b> <i class="arg">rejected</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> if the next
word is not in the set of <i class="arg">rejected</i> words, and the program is not
empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="21"><i class="arg">wipName</i> <b class="method">next</b></a></dt>
<dd><p>Returns the next word in the programm. The word is also removed.</p></dd>
<dt><a name="22"><i class="arg">wipName</i> <b class="method">peek</b></a></dt>
<dd><p>Returns the next word in the programm without removing it</p></dd>
<dt><a name="23"><i class="arg">wipName</i> <b class="method">peekall</b></a></dt>
<dd><p>Returns the remaining programm in toto.</p></dd>
<dt><a name="24"><i class="arg">wipName</i> <b class="method">insertl</b> <i class="arg">at</i> <i class="arg">wordlist</i></a></dt>
<dd><p>Basic programm accessor method. Inserts the specified <i class="arg">wordlist</i>
into the program, just before the word at position <i class="arg">at</i>. Positions
are counted from <b class="const">zero</b>.</p></dd>
<dt><a name="25"><i class="arg">wipName</i> <b class="method">replacel</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Basic programm accessor method. Replaces the whole stored program with
the specified <i class="arg">wordlist</i>.</p></dd>
<dt><a name="26"><i class="arg">wipName</i> <b class="method">pushl</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Program accessor method. The specified <i class="arg">wordlist</i> is added to the
front of the remaining program. Equivalent to</p>
<pre class="doctools_example">$wip insertl 0 $wordlist</pre>
</dd>
<dt><a name="27"><i class="arg">wipName</i> <b class="method">addl</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Program accessor method. The specified <i class="arg">wordlist</i> is appended at
the end of the remaining program. Equivalent to</p>
<pre class="doctools_example">$wip insertl end $wordlist</pre>
</dd>
<dt><a name="28"><i class="arg">wipName</i> <b class="method">insert</b> <i class="arg">at</i> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">insertl</b>, except the words are specified through
multiple arguments.</p></dd>
<dt><a name="29"><i class="arg">wipName</i> <b class="method">replace</b> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">setl</b>, except the words are specified through
multiple arguments.</p></dd>
<dt><a name="30"><i class="arg">wipName</i> <b class="method">push</b> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">pushl</b>, except the words are specified through
multiple arguments.</p></dd>
<dt><a name="31"><i class="arg">wipName</i> <b class="method">add</b> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">addl</b>, except the words are specified through
multiple arguments.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<p>No examples yet.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>wip</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#interpreter">interpreter</a>, <a href="../../../../index.html#list">list</a>, <a href="../../../../index.html#word">word</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2007-2010 Andreas Kupries &lt;andreas_kupries@users.sourceforge.net&gt;</p>
</div>
</div></body></html>
